From 6a9b72525ac5324897693d564dd283e50b58c222 Mon Sep 17 00:00:00 2001 From: Patrick Bernaud Date: Fri, 5 Mar 2010 22:58:13 +0100 Subject: [PATCH] [docs] Move documentation to inline comments: GtkSocket https://bugzilla.gnome.org/show_bug.cgi?id=611707 --- docs/reference/gtk/tmpl/gtksocket.sgml | 170 ------------------------- gtk/gtksocket.c | 71 +++++++++++ 2 files changed, 71 insertions(+), 170 deletions(-) delete mode 100644 docs/reference/gtk/tmpl/gtksocket.sgml diff --git a/docs/reference/gtk/tmpl/gtksocket.sgml b/docs/reference/gtk/tmpl/gtksocket.sgml deleted file mode 100644 index f76569311e..0000000000 --- a/docs/reference/gtk/tmpl/gtksocket.sgml +++ /dev/null @@ -1,170 +0,0 @@ - -GtkSocket - - -Container for widgets from other processes - - - -Together with #GtkPlug, #GtkSocket provides the ability -to embed widgets from one process into another process -in a fashion that is transparent to the user. One -process creates a #GtkSocket widget and, passes the -that widget's window ID to the other process, -which then creates a #GtkPlug with that window ID. -Any widgets contained in the #GtkPlug then will appear -inside the first applications window. - - - -The socket's window ID is obtained by using -gtk_socket_get_id(). Before using this function, -the socket must have been realized, and for hence, -have been added to its parent. - - -Obtaining the window ID of a socket. - -GtkWidget *socket = gtk_socket_new (); -gtk_widget_show (socket); -gtk_container_add (GTK_CONTAINER (parent), socket); - -/* The following call is only necessary if one of - * the ancestors of the socket is not yet visible. - */ -gtk_widget_realize (socket); -g_print ("The ID of the sockets window is %#x\n", - gtk_socket_get_id (socket)); - - - - - -Note that if you pass the window ID of the socket to another -process that will create a plug in the socket, you -must make sure that the socket widget is not destroyed -until that plug is created. Violating this rule will -cause unpredictable consequences, the most likely -consequence being that the plug will appear as a -separate toplevel window. You can check if the plug -has been created by examining the -plug_window field of the -#GtkSocket structure. If this field is non-%NULL, -then the plug has been successfully created inside -of the socket. - - - -When GTK+ is notified that the embedded window has been -destroyed, then it will destroy the socket as well. You -should always, therefore, be prepared for your sockets -to be destroyed at any time when the main event loop -is running. To prevent this from happening, you can -connect to the #GtkSocket::plug-removed signal. - - - -The communication between a #GtkSocket and a #GtkPlug follows the -XEmbed -protocol. This protocol has also been implemented in other toolkits, e.g. -Qt, allowing the same level of integration -when embedding a Qt widget in GTK or vice versa. - - -A socket can also be used to swallow arbitrary -pre-existing top-level windows using gtk_socket_steal(), -though the integration when this is done will not be as close -as between a #GtkPlug and a #GtkSocket. - - - -The #GtkPlug and #GtkSocket widgets are currently not available -on all platforms supported by GTK+. - - - - - - - - -#GtkPlug -the widget that plugs into a #GtkSocket. - - - -XEmbed -the XEmbed Protocol Specification. - - - - - - - - - - -The #GtkSocket structure contains the plug_window -field. (This field should be considered read-only. It should -never be set by an application.) - - - - - - - - -@socket_: - - - - - - -@socket_: -@Returns: - - - - - -@Returns: - - - - - - -@socket_: a #GtkSocket. -@wid: - - - - - - - -@socket_: -@window_id: - - - - - - - -@socket_: -@Returns: - - - - - - - -@socket_: -@Returns: - - diff --git a/gtk/gtksocket.c b/gtk/gtksocket.c index 847ee9ff01..3531af47fc 100644 --- a/gtk/gtksocket.c +++ b/gtk/gtksocket.c @@ -41,6 +41,77 @@ #include "gtkalias.h" +/** + * SECTION:gtksocket + * @Short_description: Container for widgets from other processes + * @Title: GtkSocket + * @See_also: #GtkPlug, XEmbed + * + * Together with #GtkPlug, #GtkSocket provides the ability + * to embed widgets from one process into another process + * in a fashion that is transparent to the user. One + * process creates a #GtkSocket widget and passes + * that widget's window ID to the other process, + * which then creates a #GtkPlug with that window ID. + * Any widgets contained in the #GtkPlug then will appear + * inside the first application's window. + * + * The socket's window ID is obtained by using + * gtk_socket_get_id(). Before using this function, + * the socket must have been realized, and for hence, + * have been added to its parent. + * + * + * Obtaining the window ID of a socket. + * + * GtkWidget *socket = gtk_socket_new (); + * gtk_widget_show (socket); + * gtk_container_add (GTK_CONTAINER (parent), socket); + * + * /* The following call is only necessary if one of + * * the ancestors of the socket is not yet visible. + * */ + * gtk_widget_realize (socket); + * g_print ("The ID of the sockets window is %#x\n", + * gtk_socket_get_id (socket)); + * + * + * + * Note that if you pass the window ID of the socket to another + * process that will create a plug in the socket, you + * must make sure that the socket widget is not destroyed + * until that plug is created. Violating this rule will + * cause unpredictable consequences, the most likely + * consequence being that the plug will appear as a + * separate toplevel window. You can check if the plug + * has been created by using gtk_socket_get_plug_window(). If + * it returns a non-%NULL value, then the plug has been + * successfully created inside of the socket. + * + * When GTK+ is notified that the embedded window has been + * destroyed, then it will destroy the socket as well. You + * should always, therefore, be prepared for your sockets + * to be destroyed at any time when the main event loop + * is running. To prevent this from happening, you can + * connect to the #GtkSocket::plug-removed signal. + * + * The communication between a #GtkSocket and a #GtkPlug follows the + * XEmbed + * protocol. This protocol has also been implemented in other toolkits, e.g. + * Qt, allowing the same level of integration + * when embedding a Qt widget in GTK or vice versa. + * + * A socket can also be used to swallow arbitrary + * pre-existing top-level windows using gtk_socket_steal(), + * though the integration when this is done will not be as close + * as between a #GtkPlug and a #GtkSocket. + * + * + * The #GtkPlug and #GtkSocket widgets are currently not available + * on all platforms supported by GTK+. + * + */ + /* Forward declararations */ static void gtk_socket_finalize (GObject *object); -- 2.30.2